Comments should be sent to AppleLink address OPENTPT or Internet address 'opentpt@applelink.apple.com' Unfortunately, we can not provide general technical support via this AppleLink address. Technical support questions should be directed to AppleLink address DEVSUPPORT or Internet address 'devsupport@applelink.apple.com'.
What this release contains
This release includes
• an Installer that will install Open Transport 1.0.5b2 and Apple Shared Library Manager 2.0 onto your machine.
• a Developer Files folder that contains:
• An ASLM Developer folder contain tools for developing ASLM shared libraries, as well as debugging versions of the Shared Library Manager itself.
• An Open Tpt Client Developer folder that contains documents, header files, MPW libraries, and sample programs
• An Open Tpt Module Developer folder that contains header files and libraries for creating DLPI drivers (See the document "Open Tpt Driver Dev. Note" in the documents folder.
WARNINGS
See also the ReadMe file that accompanies Open Transport
• Any code developed using the 68K interfaces for Open Transport using the SDK with this release will not be compatibile with the 1.1 release. Do not release any products for 68K Open Transport until this warning goes away.
API changes since 1.0f1
• Added kOTModLowerIsTPI, kOTModUpperIsTPI, kOTModLowerIsDLPI, kOTModLowerIsTPI flags to the flags that should be added to the install_flags field of the install_info structure.
Other changes since 1.0f1
• Timer resolution was changed from 1 milliseconds to 8 milliseconds for performance reasons. What this means is that timers will fire at the closes 8 millisecond boundary to the time requested. Any request for time less than 8 milliseconds will fire in 8 milliseconds.
.Developing Open Transport compliant protocols or drivers
This release does contain information for developers who wish to write DLPI hardware drivers for Open Transport. The document "Open Tpt Driver Dev. Note" describes the procedure for creating a loadable STREAMS module for driver writers. The document does not fully address the needs of protocol implementors, but all of the header files and libraries are present to do the development, and the differences between writing drivers and protocol modules is minimal (You can probably glean the differences by reading the "Open Tpt Driver Dev. Note" document. We still need to document how to get your module usable by the streams environment if "plumbing" is more involved than just "pushing" the module on top of a pre-existing STREAM.
All protocols in the Open Transport architecture are implemented as UNIX System V, release 4.2 STREAMS modules. Open Transport includes a standard STREAMS environment that allows STREAMS modules to be recompiled on the Macintosh. About 20 lines of code, and one ASLM “export” file have to be written to move a standard STREAMS module into the Open Transport environment.
You may want to read about UNIX STREAMS and the TPI and DLPI specifications which define the formats of messages that flow between STREAMS modules.
Sources of information that are applicable to XTI include:
- OSF/1 Operating System: Network Applications Programmer's Guide; Open Software Foundation, Prentice Hall, ISBN 0-13-640145-7
- UNIX Network Programming; W. Richard Stevens, Prentice Hall, ISBN 0-13-949876-1
- Programming UNIX SVR4.2: Network Programming Interhces; UNIX Press (A Prentice Hall title), ISBN 0-13-017641-9
- X/Open CAE Specification: X/Open Transport Interface (XTI); X/Open Company, Ltd. (XO/CAE/91/600) ISBN 1-872630-29-4 (also available on E•T•O in electronic form)
Sources of information that are applicable to STREAMS modules and drivers include:
-STREAMS Modules and Drivers, UNIX SVR4.2; UNIX Press (A Prentice Hall title), ISBN 0-13-066879-6. A much improved revision to the former Programmer’s Guide for STREAMS (listed below). It also includes the TPI specification and a description of DLPI.
- UNIX System V Relase 4: Programmer's Guide: STREAMS; Unix Press (A Prentice Hall title), ISBN - 0-13-020660-1
-UNIX System V Network Programming; Stephen A. Rago, Addison-Wesley Publishing Company, ISBN 0-201-56318-5. A good book for learning to write STREAMS modules and drivers. The book contains (among other things) a discussion of TLI (precursor to XTI) and a complete DPLI STREAMS driver for Ethernet.
- Transport Provider Interface Specification, revision 1.5 (92/12/10); UNIX International, OSI Special Interest Group (also available on E•T•O in electronic form)
- Data Link Provider Interface Specification, revision 2.0.0 (91/08/20); UNIX International, OSI Work Group (also available on E•T•O in electronic form)
Debugger support
The installer will install Open Transport Debugger preferences into the DebuggerPrefs file in your System Folder, if you have one. These debugger prefs contain the ASLM debugger prefs plus Macsbug templates for virtually all structures used in the API. A Macbug dcmd is installed also that can display strings for error messages. For example, typing “OTErr -3158” will tell you what error number -3158 is.
Sample Code
There is a "Samples" folder which contains sample modules and source files.
All of the samples have makefiles that can be used to build them. All of the makefiles use shell variables that must be set to the full pathname of the folders containing the Apple Shared Library Manager and Open Transport header files and object libraries. If you drag the header files and object files from the developer tools diskette to the normal places in MPW, you’d want to set up the shell variables like this before building.
Set ASLMIncludes “{CIncludes}”
Set OTIncludes “{CIncludes}”
Set OTModIncludes “{CIncludes}”
Set OTLibs “{CLibraries}”
Set ASLMLibs “{CLibraries}”
Export ASLMIncludes OTIncludes OTLibs ASLMLibs
After doing this,you can build the sample programs by setting your current MPW directory to be the one containing the samples and using the ‘make’ tool:
Make -f Makefile.SampleModules
OpenTransport header files require the header files that were released on E.T.O. #15 in the "Latest MPW" folder.
Earlier Release Notes
API changes since 1.0b3
• There was some confusion over the kOTModIsPortDriver bit being dropped and adding a kOTModIsComplexDriver bit. Here's the deal: For standard drivers that can just be "opened" by STREAMS, you should just have the kOTModIsDriver bit set in your install_info. This means that the kOTModIsPortDriver which you used to also set should just be removed.
The kOTModIsComplexDriver bit is a flag to tell Open Transport that when someone wants to open your driver, it is more complicated than just a simple stream open call (an example would be an IPCP driver, which is an IP-related driver that sits on top of PPP and a serial port - It needs to be "pushed" or "linked" with PPP, and then it is clone-opened) . Instead, a "Configurator" is required. The "Configurator" architecture is in the process of being documented, and some documentation should be available by late June.
Other changes since 1.0b3
• Many of the utility functions that are used by STREAM modules used to be in a library called OTUtilityLib that was shared between client and kernel code. Since under Copland, it may not be feasible to share all of this code, OTUtilityLib functions are now exported through the OTKernelLib to allow us to change where the function is implemented without modules having to change. HOWEVER, this means that modules linked with prior version of Open Transport will not work with this version and need to be relinked (If you are linked with 1.0b4 or higher, you can disregard this).
API changes since 1.0b2
NOTE: you should also read the OT Client Release Notes file
• The TPortRecord structure was modified to include an fStreamtab field so that drivers can get to the "real" streamtab being used by Open Transport, if necessary.
• The kOTModIsPortDriver flag for the install_flags in GetOTInstallInfo was dropped. It was never being used by Open Transport. Instead a kOTModIsComplexDriver bit was added to tell Open Transport that the driver is more complicated than just "opening" it.
• The TerminateStreamModule call is now passed the contextPtr (a PCIInfo structure pointer for PCI drivers). This is so that ASLM drivers can recover their context (ASLM drivers don't have per-instantiation globals like CFM drivers do).
Other changes since 1.0b2
• When instantiating a second instance of a CFM module or driver, use the kNewCFragCopy load option so that a new copy of global variables is created for the module/driver.
API changes since 1.0b1
• The TPortRecord structure was modified.
• OTEnterDeferredTask/OTLeaveDeferredTask were renamed to OTEnterCriticalSection/OTLeaveCriticalSection.
Other changes since 1.0b1
• A module returning kENOENTErr from it's ValidateHardware routine will now cause Open Transport to try and find another driver that works.
API changes since 1.0a3
• The OTAllocPortMem and OTFreePortMem functions were added to better support port scanners on non-PCI systems. Using these functions instead of OTAllocMem and OTFreeMem keep the whole STREAMS infrastructure from being loaded when it is not needed.
• The OTLIFO structure was not obsoleted as planned. OTLIFO and OTList still exist separately. There are now no plans to obsolete OTLIFO.
• OTList was changed to a singly-linked list from a doubly-linked list, and the API changed accordingly.
• OTAcquireLock and OTClearLock were added. In this release, they are just front-ends to the atomic set bit instructions. In the next release, OTAcquireLock will be implemented as an actual function. The main reason for this change is that OTAcquireLock can be implemented to have a much short interval where the lock must be retried than is possible with the atomic bit instructions.
• Several new APIs were added to OpenTptModule.h
• OTFindPortByDev now only takes 1 parameter. The 2nd parameter was returning a value that can be determined by inspecting the TPortRecord returned.
• OTEnterInterrupt and OTLeaveInterrupt now take no parameters.
• EnterOTContext and LeaveOTContext were dropped, and are not needed.
• OTDestroyDeferredTask now returns an OSStatus value. OTDestroyDeferredTask may return kEAGAINErr if you are trying to destroy the deferred task while it is scheduled (this can only happen of you destroy the deferred task from within an interrupt service routine or another deferred task, which is rare)
• STREAM drivers are no longer required to call OTInitModule or OTTerminateModule - they still exist for compatibility, but do nothing.
• A new device equate was added for 100 MB Ethernet
• Support for ValidateHardware returning kENOENTErr (the "it's not my hardware" error) has been added.
• Support for Ethernet "Raw Mode" was added via an IOCTL call
• When PCI drivers are loaded, their complete closure is now locked down in memory.
Other changes since 1.0a3
• The Open Tpt Ethernet Dev. Note has been updated to better describe IPX support.
• "Raw mode" support was added for link-layer drivers. See the Open Tpt Ethernet Dev. Note and the Open Tpt 8022 Dev. Note for details.
• The Open Tpt Module Dev. Note is still a placeholder. It contains the prior contents of the Open Tpt Driver Dev. Note.
• For drivers, the only "put" routine is allowed at primary interrupt time is a "putq" to your own lower queue. This allowed us to take out special code that slows things down in all the other "put" routines. You can always schedule your own deferred task to make one of the other "put" function calls.
• OTAllocMsg now uses the "esballoc" function instead of the "esballoca" function. What this means is that clients are now allowed to overwrite data in your buffers until the buffer is freed. If this is not desireable, use esballoca directly.
